<html><!-- Copyright (C) 2007 Laurent A.V. Szyster - Copylef GPL 2.0 -->
<head>
  <title>protocols.js > Functions</title>
  <link href="site.css" type="text/css" rel="stylesheet"></link>
  <link href="protocols.css" type="text/css" rel="stylesheet"></link>
</head>
<body>
<div>  
  <h1><a href="index.html">protocols.js</a></h1>
  <div class="menu">
    <a href="documentation.html">Documentation</a> &gt;
    <a href="HTTP.html">HTTP</a>
    <a href="HTML.html">HTML</a>
    <a href="CSS.html">CSS</a>
    <a href="JSON.html">JSON</a>
  </div>
  <h2>Functions</h2>
  <ol>
    <li><a href="#pass">pass ()</a></li>
    <li><a href="#map">map (fun, list)</a></li>
    <li><a href="#filter">filter (fun, list)</a></li>
    <li><a href="#$">$ (id)</a></li>
    <li><a href="#$$">$$ (selector, element)</a></li>
    <li><a href="#bindAsEventListener"
    >bindAsEventListener (object, fun, bubble, capture)</a></li>
    <li><a href="#Protocols">Protocols ()</a></li>
  </ol>
  <h3>Synopsis</h3>
  <p>
    Protocols adds a few functions to the JavaScript globals.
    Three are simple functional tools - <code>pass</code>, <code>map</code> 
    and <code>filter</code>, two are Prototype's widely adopted semantics -
    <code>$</code> and <code>$$</code>, the last one is a convenience for
    prototype mix-in that also serve as root for general purpose library
    properties.
     
  </p>
  <h3><a name="pass" href="#">pass ()</a></h3>
  <p>
    As its name implies, this function does nothing. 
  </p>
  <pre>function continue_this (maybe_undefined) {
    (maybe_undefined || <strong>pass</strong>)(some, argument);
}</pre>
  <p>
    Its purpose is to be used as a default function in place where a 
    continuation may be undefined.
  </p>
  <h3><a name="map" href="#">map (fun, list)</a></h3>
  <pre
    class="synopsis"
    onclick="HTML.update($('functions_map'), JSON.encode(eval_synopsis(this)))"
    >function double (what) {
    return what + what;
};
<strong>map(</strong>double, [1,2,"World!"]<strong>)</strong>;</pre>
  <div id="functions_map" class="test">...</div>
  <h3><a name="filter" href="#">filter (fun, list)</a></h3>
  <pre
    class="synopsis" 
    onclick="HTML.update($('functions_filter'), JSON.encode(eval_synopsis(this)))"
    >function odd (number) {
    return ((number % 2) != 0);
}; 
<strong>filter(</strong>odd, [0,1,2,3,4,5,6,7,8,9]<strong>)</strong>;</pre>
  <div id="functions_filter" class="test">...</div>
  <h3><a name="$" href="#">$ (id)</a></h3>
  <p>
    Unless you are totally new to JavaScript you may (think you) know the
    purpose of this function. The implementation of <code>protocols.js</code> 
    is a pure convenience, a typing shortcut:
  </p>
  <pre>function <strong>$(id)</strong> {
    return document.getElementById(id);
}</pre>
  <p>
    So, users of <code>prototype.js</code> should note that this 
    implementation does not accept more than one argument and allways 
    returns <code>null</code> or the DOM node identified (i.e.: <em>not a
    <a 
      href="http://www.jackslocum.com/blog/2006/11/06/rambling-at-400am-design-patterns-in-javascript-jquery-style-selectors-zebra-stripes/"
      >composite</a> instance</em>).
  </p>
  <h3><a name="$$" href="#">$$ (selector, element)</a></h3>
  <p>
    A typing shortcut again, with a name inspired by the API of 
    <code>prototype.js</code>:
  </p>
  <pre>function <strong>$$(selector, element)</strong> {
    return CSS.select(selector, element);
}</pre>
  <p>
    See: <code><a 
    href="CSS.html#CSS.select"
    >CSS.select</a></code> for more information.
  </p>
  <h3><a name="bindAsEventListener" href="#"
  >bindAsEventListener (object, fun, bubble, capture)</a></h3>
  <p>
    Bind an object as the first argument of a function that expects as
    second argument an event. It is applied to bind a function to an
    object and then attach it as an event listener to an element of the 
    document. The last two arguments - bubble and capture - are optional.
    To prevent the propagation of the event, set <code>bubble</code> 
    to false. To prevent the default action to take place, set 
    <code>capture</code> to true.
  </p>
  <pre id="bindAsEvenListener_test" class="synopsis" onclick="eval_synopsis(this);"
    >var listener = <strong>bindAsEventListener(</strong>
    {who: 'world!'}, function (event) {alert('hello ' + this.who);}
    <strong>);</strong>
HTML.listen ($('bindAsEvenListener_test'), 'click', listener);</pre>
  <p>
    The last two arguments - bubble and capture - are optional.
    To prevent the propagation of the event, set <code>bubble</code> 
    to false. To prevent the default action to take place, set 
    <code>capture</code> to true.
  </p>
  <pre id="bindAsEvenListener_test" class="synopsis" onclick="eval_synopsis(this);"
    >var listener = <strong>bindAsEventListener(</strong>
    {who: 'world!'}, function (event) {alert('hello ' + this.who);}
    <strong>);</strong>
HTML.listen ($('bindAsEvenListener_test'), 'click', listener);</pre>
  <p>
    Users of <code>prototype.js</code> should note that this implementation
    is somewhat simpler that the one coming with version 1.5.0 of their
    favorite JavaScript library.
  </p>
  <h3><a name="Protocols" href="#">Protocols ()</a></h3>
  <p>
    The last global function is a simple convenience to mix-in objects and 
    return a new <a 
    href="http://blog.morrisjohns.com/illumination_on_javascript_prototypes?PHPSESSID=bf6155e4cd8b01d2c7f2151525041429"
    >prototype</a>.
  </p>
  <pre class="synopsis" onclick="eval_synopsis(this);"
    >var A = {
    initialize: function (who) {
        this.who = who;
    }
}
var B = {
    hello: function () {
        alert ('hello ' + this.who);
    }
}
C = <strong>Protocols (</strong>A, B<strong>)</strong>;
world = new C('world!')
world.hello();</pre>
  <p>
    Elaborate object protocols are possible in JavaScript, this is just a 
    functional convenience <em>for</em> JavaScript.
    This function expects a constructor named <code>initialize</code> from 
    one of the protocols mixed in, supports composition only and resolves
    name conflict simply: the last interface mixed-in overrides the previous 
    one(s).
  </p>
</div>
<script src="protocols.js" type="text/javascript"></script>
<script src="tests.js" type="text/javascript"></script>
</body>
</html>